---
title: Environment Variables
description: Using built-in and custom environment variables in Terrateam workflows and hooks
---

Environment variables play a crucial role in configuring and customizing Terrateam workflows and hooks. Terrateam provides a set of built-in environment variables that you can use to access information about the current workflow execution context and the results of Terrateam operations. Additionally, you can define your own custom environment variables to store and pass data between different steps and stages of your Terrateam pipelines.

## Built-in Environment Variables
Terrateam provides the following built-in environment variables:

### Workflow Environment Variables
| Name | Description |
|------|-------------|
| `TERRATEAM_PLAN_FILE` | The path to the generated Terraform plan file. |
| `TERRATEAM_DIR` | The working directory relative to the root of the repository. |
| `TERRATEAM_WORKSPACE` | The Terraform workspace being executed against. |
| `TERRATEAM_ROOT` | The absolute path to the root of your checked-out repository. |

### Post-hook Environment Variables
| Name | Description |
|------|-------------|
| `TERRATEAM_RESULTS_FILE` | The path to a JSON file that contains the results of all executed dirspaces. |

<details>
  <summary>Expand for example TERRATEAM_RESULTS_FILE</summary>
  ```json
{
    "dirspaces": [
        {
            "path": "database",
            "workspace": "default",
            "success": true,
            "outputs": [
                {
                    "workflow_step": {
                        "type": "run",
                        "cmd": [
                            "tofu",
                            "init"
                        ],
                        "exit_code": 0
                    },
                    "success": true,
                    "outputs": {
                        "output_key": "init",
                        "text": "\r                                                                           0.1%\r######################################################################## 100.0%\n\nInitializing the backend...\n\nInitializing provider plugins...\n- Finding latest version of hashicorp/null...\n- Installing hashicorp/null v3.2.2...\n- Installed hashicorp/null v3.2.2 (signed, key ID 0C0AF313E5FD9F80)\n\nProviders are signed by their developers.\nIf you'd like to know more about provider signing, you can read about it here:\nhttps://opentofu.org/docs/cli/plugins/signing/\n\nOpenTofu has created a lock file .terraform.lock.hcl to record the provider\nselections it made above. Include this file in your version control repository\nso that OpenTofu can guarantee to make the same selections by default when\nyou run \"tofu init\" in the future.\n\nOpenTofu has been successfully initialized!\n"
                    }
                },
                {
                    "workflow_step": {
                        "type": "plan"
                    },
                    "success": true,
                    "outputs": {
                        "plan": "\nOpenTofu used the selected providers to generate the following execution\nplan. Resource actions are indicated with the following symbols:\n  + create\n\nOpenTofu will perform the following actions:\n\n  # null_resource.foo will be created\n  + resource \"null_resource\" \"foo\" {\n      + id = (known after apply)\n    }\n\nPlan: 1 to add, 0 to change, 0 to destroy.\n",
                        "plan_text": "\nOpenTofu used the selected providers to generate the following execution\nplan. Resource actions are indicated with the following symbols:\n  + create\n\nOpenTofu will perform the following actions:\n\n  # null_resource.foo will be created\n  + resource \"null_resource\" \"foo\" {\n      + id = (known after apply)\n    }\n\nPlan: 1 to add, 0 to change, 0 to destroy.\n",
                        "has_changes": true
                    }
                }
            ]
        }
    ],
    "overall": {
        "success": true
    }
}
```
</details>

### GitHub Actions Environment Variables
In addition to the Terrateam-specific environment variables, you also have access to the default environment variables provided by GitHub Actions. Refer to the [GitHub documentation](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables) for a complete list of available variables.

## Custom Environment Variables
Terrateam allows you to define your own custom environment variables in your [workflows](/reference/configuration/workflows) and [hooks](/reference/configuration/hooks). You can use custom environment variables to store and pass data between different steps, set configuration options, or provide dynamic values based on the execution context.

### Defining Custom Environment Variables in Workflows
To define custom environment variables in your Terrateam workflows, you can use the `env` step type. Here's an example workflow configuration that sets a custom environment variable:
```yaml
workflows:
  - tag_query: ""
    plan:
      - type: env
        name: MY_CUSTOM_VAR
        cmd: ['echo', 'Hello, World!']
      - type: run
        cmd: ['echo', 'The value of MY_CUSTOM_VAR is: $MY_CUSTOM_VAR']
```
In this example, the `env` step sets a custom environment variable named `MY_CUSTOM_VAR` with the value "Hello, World!". The subsequent `run` step can then access the value of `MY_CUSTOM_VAR` using the `$` prefix.

### Defining Custom Environment Variables in Hooks
Similarly, you can define custom environment variables in your Terrateam hooks using the `env` hook type. Here's an example hook configuration that sets a custom environment variable:
```yaml
hooks:
  plan:
    pre:
      - type: env
        name: MY_HOOK_VAR
        cmd: ['echo', 'Hello from the pre-plan hook!']
    post:
      - type: run
        cmd: ['echo', 'The value of MY_HOOK_VAR is: $MY_HOOK_VAR']
```
In this example, the `env` hook in the `pre` section of the `plan` hook sets a custom environment variable named `MY_HOOK_VAR` with the value "Hello from the pre-plan hook!". The `run` hook in the `post` section can then access the value of `MY_HOOK_VAR`.

### Using Custom Environment Variables
Once you have defined your custom environment variables, you can use them in your Terrateam configurations and scripts by referencing them with the `$` prefix followed by the variable name. For example:
```yaml
workflows:
  - tag_query: ""
    plan:
      - type: run
        cmd: ['echo', 'The value of MY_CUSTOM_VAR is: $MY_CUSTOM_VAR']
```
In this example, the `$MY_CUSTOM_VAR` variable will be expanded to the actual value of the `MY_CUSTOM_VAR` environment variable during execution.

## Best Practices
When using environment variables, keep the following best practices in mind:
- Use meaningful and descriptive names for your own custom environment variables to avoid conflicts with Terrateam's built-in variables or other system variables.
- Be cautious when using environment variables to store sensitive information, such as secrets or credentials. Instead, consider using secure mechanisms like Terrateam's integration with GitHub Secrets or a secrets management system.
- Ensure that your scripts and configurations handle missing or empty environment variables gracefully to avoid unexpected errors or behavior.
